RSS Feed Generation

**Referenced Files in This Document** - [feed.njk](file://src/feed.njk) - [.eleventy.js](file://.eleventy.js) - [site.json](file://src/_data/site.json) - [news.11tydata.json](file://src/content/news/news.11tydata.json) - [2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md) - [2025-11-03-political-stalwart.md](file://src/content/news/2025-11-03-political-stalwart.md) - [package.json](file://package.json)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document explains how the RSS feed generation system works in this Eleventy project. It focuses on the feed.njk template that produces an Atom XML feed for news content, how Eleventy’s collection system feeds the template, and how feed metadata is configured via global site data. It also covers feed URL structure, content formatting, syndication best practices, customization tips, validation, caching strategies, and integration with external RSS readers.

Project Structure

The feed is implemented as a standalone Nunjucks template with front matter that defines its output path and exclusion from Eleventy collections. The Eleventy configuration defines the news collection, while site-wide metadata comes from a shared data file. News content is stored under src/content/news with individual Markdown files that include front matter for dates, titles, excerpts, and optional flags.

graph TB
subgraph "Eleventy Configuration"
ELE[".eleventy.js<br/>Defines collections and transforms"]
end
subgraph "Data Layer"
SITE["src/_data/site.json<br/>Site metadata (title, description, url)"]
NEWSMETA["src/content/news/news.11tydata.json<br/>Per-collection options"]
end
subgraph "Content"
NEWS1["src/content/news/2025-10-17-political-powerhouse.md"]
NEWS2["src/content/news/2025-11-03-political-stalwart.md"]
end
subgraph "Feed Template"
FEED["src/feed.njk<br/>Atom XML feed template"]
end
ELE --> FEED
SITE --> FEED
NEWSMETA --> ELE
ELE --> NEWS1
ELE --> NEWS2
FEED --> |"Generates"| OUT["_site/feed.xml"]

Diagram sources

  • [feed.njk](file://src/feed.njk)
  • [.eleventy.js](file://.eleventy.js)
  • [site.json](file://src/_data/site.json)
  • [news.11tydata.json](file://src/content/news/news.11tydata.json)
  • [2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md)
  • [2025-11-03-political-stalwart.md](file://src/content/news/2025-11-03-political-stalwart.md)

Section sources

  • [feed.njk](file://src/feed.njk)
  • [.eleventy.js](file://.eleventy.js)
  • [site.json](file://src/_data/site.json)
  • [news.11tydata.json](file://src/content/news/news.11tydata.json)

Core Components

  • Atom feed template: The feed.njk template renders an Atom feed with metadata from site data and entries from the news collection. It sets the feed URL as the self link and includes author, updated timestamps, and entries with titles, links, publication dates, and content.
  • Eleventy collections: The .eleventy.js configuration defines a news collection that loads Markdown files from src/content/news and sorts them by date descending. This collection powers the feed entries.
  • Site metadata: The src/_data/site.json file supplies the feed title, subtitle, base URL, and language used in the feed.
  • Content front matter: Each news article’s front matter includes a publish date and other fields consumed by the feed template.

Key behaviors:

  • Feed URL: Permalink is set to /feed.xml, so the feed is generated at example.com/feed.xml.
  • Entry sorting: The template iterates over the news collection in reverse order to show newest posts first.
  • Updated timestamp: The feed’s updated element is set to the latest post’s date or a fallback date if no posts exist.
  • Content: The entry content is emitted as CDATA from the template’s compiled HTML.

Section sources

  • [feed.njk](file://src/feed.njk)
  • [.eleventy.js](file://.eleventy.js)
  • [site.json](file://src/_data/site.json)
  • [2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md)
  • [2025-11-03-political-stalwart.md](file://src/content/news/2025-11-03-political-stalwart.md)

Architecture Overview

The feed generation pipeline connects Eleventy’s data and collections to the feed template and outputs an Atom XML feed.

sequenceDiagram
participant E as "Eleventy Config (.eleventy.js)"
participant D as "Site Data (site.json)"
participant N as "News Content (*.md)"
participant T as "Feed Template (feed.njk)"
participant O as "Output (_site/feed.xml)"
E->>N : Load and sort news collection
E->>T : Provide collections.news
D->>T : Inject site.title, site.description, site.url
T->>O : Render Atom XML with entries

Diagram sources

  • [.eleventy.js](file://.eleventy.js)
  • [site.json](file://src/_data/site.json)
  • [feed.njk](file://src/feed.njk)

Detailed Component Analysis

Feed Template (feed.njk)

Responsibilities:

  • Define feed metadata: title, subtitle, self link, alternate link, author, and feed ID.
  • Compute the feed updated timestamp from the newest news item or a fallback.
  • Iterate over the news collection in reverse chronological order to produce entries.
  • Emit each entry’s title, link, updated date, unique ID, and content as CDATA.

Important template-level behaviors:

  • Permalink: The front matter sets the output path to /feed.xml.
  • Exclusion: The template is excluded from Eleventy collections to avoid duplication.
  • Collection access: Uses collections.news to iterate over posts.
  • Date handling: Uses post.date and converts to ISO string for Atom.
  • Content emission: Uses templateContent with safe filter to output raw HTML as CDATA.

Customization hooks visible in the template:

  • Title and subtitle come from site metadata.
  • Author name is taken from site title.
  • Link elements point to the site URL and the news listing page.
  • Entry IDs combine the site URL with the post’s file slug.

Section sources

  • [feed.njk](file://src/feed.njk)

Eleventy Collections (.eleventy.js)

Responsibilities:

  • Register a news collection that reads Markdown files from src/content/news.
  • Sort posts by date descending so the newest appear first.
  • Provide the collection to templates via collections.news.

Integration with the feed:

  • The feed template relies on this collection being populated and sorted.

Extensibility:

  • Other collections exist (cases, newsletters, teamMembers, featuredNews, services, knowledge) but are not used by the feed template.

Section sources

  • [.eleventy.js](file://.eleventy.js)

Site Metadata (site.json)

Responsibilities:

  • Provide the feed’s title, description, base URL, and language.
  • Supply author name and other branding fields used by the feed.

Impact on feed:

  • The feed title and subtitle reflect site.title and site.description.
  • The feed’s self link and alternate link use site.url.
  • The author’s name is derived from site.title.

Section sources

  • [site.json](file://src/_data/site.json)

Content Front Matter (news/*.md)

Responsibilities:

  • Define per-post metadata used by the feed: title, date, excerpt, and optional flags.
  • Enable sorting and filtering via the Eleventy collection.

Examples:

  • Two news posts demonstrate typical front matter with title, date, author, excerpt, and optional flags.

Section sources

  • [2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md)
  • [2025-11-03-political-stalwart.md](file://src/content/news/2025-11-03-political-stalwart.md)

Feed URL Structure and Output Location

  • The feed is generated at /feed.xml because the template’s front matter sets permalink to /feed.xml.
  • The output file appears in the _site directory after building.

Syndication note:

  • The template sets a self link to the feed URL and an alternate link to the home page. This is standard for Atom feeds.

Section sources

  • [feed.njk](file://src/feed.njk)

Content Formatting and Syndication Best Practices

Observed behavior:

  • Entry content is emitted as CDATA containing the compiled HTML from the post’s templateContent.
  • Dates are emitted in ISO 8601 format, suitable for Atom feeds.
  • The feed includes a single author with the site title as the author name.

Recommendations (best practice):

  • Use proper Atom namespaces and ensure the feed declares the Atom namespace.
  • Consider adding a generator tag to identify the platform.
  • Ensure entry IDs are globally unique; the current template uses a combination of the site URL and the post’s file slug.
  • Include summary excerpts in addition to full content for reader efficiency.
  • Add category elements per entry if content is categorized.
  • Validate the feed using an online validator to confirm compliance.

[No sources needed since this section provides general guidance]

Customizing Feed Content

Examples of customizations you can apply:

  • Add categories to entries: Extend the template to emit category elements for each entry using post.data.categories.
  • Include excerpts: Add a subtitle or summary field to the entry content.
  • Adjust author attribution: Use post.data.author or a dedicated author field if present.
  • Control entry ordering: The template currently reverses the collection; keep this to show newest first.
  • Modify content type: Change content type to text or html depending on your preference.

Implementation tip:

  • Keep changes localized to the feed template to avoid impacting other parts of the site.

[No sources needed since this section provides general guidance]

Adding Categories to Entries

Approach:

  • Ensure news posts include a categories field in their front matter.
  • Extend the feed template to loop over categories and emit atom:category elements for each entry.

Example pattern:

  • Use a loop over post.data.categories and render category elements with appropriate term and label attributes.

[No sources needed since this section provides general guidance]

Troubleshooting Common Feed Generation Issues

  • Empty or missing entries:
    • Verify the news collection is populated and sorted correctly in .eleventy.js.
    • Confirm that news content files exist under src/content/news and include valid front matter dates.
  • Incorrect updated timestamp:
    • The feed uses the latest post’s date; ensure posts have valid dates.
  • Broken links:
    • The template emits a link to the news listing page; confirm the news page exists and is reachable.
  • Content not rendering:
    • The template uses templateContent with safe; ensure the post compiles to HTML.
  • Feed not appearing at /feed.xml:
    • Confirm the template’s permalink front matter is set to /feed.xml and that the template is not excluded from collections (it is intentionally excluded from Eleventy collections for feed generation).

Section sources

  • [.eleventy.js](file://.eleventy.js)
  • [feed.njk](file://src/feed.njk)

Dependency Analysis

External dependency relevant to RSS:

  • The project includes @11ty/eleventy-plugin-rss, indicating awareness of Eleventy’s RSS ecosystem. While this project uses a custom feed.njk template, the plugin is present and could be leveraged for standardized RSS generation if desired.
graph LR
P["package.json<br/>Dependencies"]
R["@11ty/eleventy-plugin-rss"]
F["feed.njk"]
E[".eleventy.js"]
P --> R
E --> F

Diagram sources

  • [package.json](file://package.json)
  • [feed.njk](file://src/feed.njk)
  • [.eleventy.js](file://.eleventy.js)

Section sources

  • [package.json](file://package.json)

Performance Considerations

  • Feed size: The feed includes full compiled HTML content for each entry. For large posts, this can increase feed size. Consider trimming content or using excerpts if feed size becomes a concern.
  • Sorting cost: The news collection is sorted by date; this is efficient for moderate content volumes. For very large collections, consider pagination or limiting the number of entries in the feed.
  • Build time: Feeds are generated during Eleventy builds. Keep front matter minimal and avoid heavy filters in the feed template to reduce build time.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Feed not found:
    • Confirm the feed template’s permalink is /feed.xml and that the build completes without errors.
  • Invalid XML:
    • Validate the generated feed using an Atom/RSS validator. Ensure all tags are properly closed and namespaces are correct.
  • Incorrect dates:
    • Ensure posts have valid dates in front matter and that the collection sorts by date.
  • Missing content:
    • Verify that posts compile to HTML and that templateContent is available.

Validation checklist:

  • Use an online Atom validator to check well-formedness.
  • Confirm the self link and alternate link are correct.
  • Ensure entry IDs are unique and stable.

Section sources

  • [feed.njk](file://src/feed.njk)
  • [.eleventy.js](file://.eleventy.js)

Conclusion

The project generates an Atom XML feed using a dedicated feed.njk template that pulls from Eleventy’s news collection and site metadata. The configuration is straightforward: a single template with front matter controls the output path, while .eleventy.js defines the news collection and site.json supplies branding and URLs. The approach is simple and effective, suitable for small to medium-sized sites. For advanced needs, consider integrating @11ty/eleventy-plugin-rss or extending the template to support categories, excerpts, and pagination.